~ chicken-core (chicken-5) /manual/Module (chicken gc)

  1[[tags: manual]]
  2[[toc:]]
  3
  4== Module (chicken gc)
  5
  6This module provides some control over the garbage collector.
  7
  8=== gc
  9
 10<procedure>(gc [FLAG])</procedure>
 11
 12Invokes a garbage-collection and returns the number of free bytes in the heap.
 13The flag specifies whether a minor ({{#f}}) or major ({{#t}}) GC is to be
 14triggered. If no argument is given, {{#t}} is assumed. An explicit {{#t}}
 15argument will cause all pending finalizers to be executed.
 16
 17=== current-gc-milliseconds
 18
 19<procedure>(current-gc-milliseconds)</procedure>
 20
 21Returns the number of milliseconds spent in major garbage collections since
 22the last call of {{current-gc-milliseconds}} and returns an exact
 23integer.
 24
 25=== memory-statistics
 26
 27<procedure>(memory-statistics)</procedure>
 28
 29Performs a major garbage collection and returns a three element vector
 30containing the total heap size in bytes, the number of bytes currently
 31used and the size of the nursery (the first heap generation). Note
 32that the actual heap is actually twice the size given in the heap size,
 33because CHICKEN uses a copying semi-space collector.
 34
 35
 36=== set-finalizer!
 37
 38<procedure>(set-finalizer! X PROC)</procedure>
 39
 40Registers a procedure of one argument {{PROC}}, that will be
 41called as soon as the non-immediate data object {{X}} is about to
 42be garbage-collected (with that object as its argument).
 43This procedure returns {{X}}.
 44
 45Finalizers installed using {{set-finalizer!}} are invoked asynchronously,
 46in the thread that happens to be currently running.
 47Finalizers for data that has become garbage
 48are called on normal program exit. Finalizers are not run on
 49abnormal program exit. A normal program exit does not run finalizers
 50that are still reachable from global data.
 51
 52Multiple finalizers can be registered for the same object. The order
 53in which the finalizers run is undefined. Execution of finalizers
 54may be nested.
 55
 56NOTE 1: The finalizer will '''not''' be called while interrupts are disabled.
 57
 58NOTE 2: When a finalizable object has any weak references (i.e., weak
 59locatives or weak pairs) to objects that are only reachable through it
 60or other finalizable objects, those references will be broken like
 61when the objects had already been collected.  This is done in order to
 62avoid user code from accessing objects that are possibly in an
 63invalid state.
 64
 65
 66=== make-finalizer
 67
 68<procedure>(make-finalizer OBJECT ...)</procedure>
 69
 70Registers the set of non-immediate argument objects for finalization and
 71returns a procedure of zero or one arguments. Invoking this procedure
 72will return the first object from the set that
 73is not referenced from any other globally reachable data and can be
 74garbage collected.
 75Non-immediate objects are anything that is not a small integer ("fixnum"),
 76a character, a boolean, the empty list, the undefined value, the end-of-file
 77value ({{#!eof}}) or the broken-weak-pair object ({{#!bwp}}).
 78
 79Note that you can pass procedures created by {{make-finalizer}} to
 80{{make-finalizer}} itself, implying that a finalizer procedure is finalized
 81when all associated objects are.
 82
 83The procedure returned by {{make-finalizer}} behaves differently
 84depending on the argument given: If the argument is missing or {{#f}},
 85then it returns {{#f}} when no object has as yet been finalized.
 86When the argument is {{#t}}, execution of the current thread suspends until a finalization
 87occurs. If no other threads are executing then execution pauses for eternity.
 88
 89The same caveat regarding weak references applies to finalizers
 90registered with {{make-finalizer}}.  See {{NOTE 2}} in {{set-finalizer!}}.
 91
 92=== add-to-finalizer
 93
 94<procedure>(add-to-finalizer FINALIZER OBJECT ...)</procedure>
 95
 96Add further objects to the finalization procedure {{FINALIZER}}, in
 97addition to the objects already supplied when invoking {{make-finalizer}}.
 98
 99=== force-finalizers
100
101<parameter>(force-finalizers)</parameter>
102
103If true, force and execute all pending finalizers before exiting the
104program (either explicitly by {{exit}} or implicitly when the last
105toplevel expression has been executed). Default is {{#t}}.
106
107
108=== set-gc-report!
109
110<procedure>(set-gc-report! FLAG)</procedure>
111
112Print statistics after every GC, depending on {{FLAG}}. A value of
113{{#t}} shows statistics after every major GC. A true value different
114from {{#t}} shows statistics after every minor GC. {{#f}}
115switches statistics off.
116
117
118---
119Previous: [[Module (chicken format)]]
120
121Next: [[Module (chicken io)]]